!OSLib.docs.OSLib_readme 20020410

Introduction
------------
  OSLib is a set of functions  and C headers to provide complete coverage  of
the RISC O S application programmer's interface in C. It provides access from
C code to all RISC O S system calls ("SWI's") which is

      efficient: often, memory access is completely avoided;

      type-safe: every argument can be type-checked by the compiler;

      obvious: a SWI is called by the "obvious" syntax;

      complete: every SWI is covered;

      register-safe: hides (often idiosyncratic) register allocation;

      language-independent: although the  headers are specific to C,  the
      library is not - any A P C S-conformant language can call it.

  It also provides names for all the data structures and reason codes used by
the A P I. Code that uses it is superior  to similar code using _kernel_swi()
or _swix(), both in terms of the compile-time checking that is available, and
the size and speed of the code generated.

  OSLib  provides a  very convenient  interface to  the RISC  O S programmer,
since all the facilities of the  C compiler are available to catch errors and
generate good  code. It is conceptually very small,  in that it is completely
documented  by this file. As  a bonus, code  written using it  is smaller and
faster than code written using other means.

  OSLib is copyright © 1994-2002  Jonathan Coxhead and OSLib maintainers.  It
is distributed in the hope that it will be useful, but  without any warranty;
without  even the  implied  warranty  of  merchantability or  fitness  for  a
particular purpose.

  OSLib is released under the GNU  public licence - for details see the  file
"copying" included with  this release. The  copyright holders have granted  a
relaxation of the conditions of this licence to allow its use in constructing
proprietary  software.  This means  that  it  is  free software  itself,  but
applications linked to it need not be.  It follows that any changes to  OSLib
itself (the contents of the directories Tools, Source, and OSLibSupport) fall
under the terms of the GNU Public Licence; but programmes written using OSLib
do not.

  Fault  reports  and  suggestions  for  improvement  may  be  sent   to  the
maintainers, mailto:<oslib-user@compton.nu>.

A number of mail lists have been set up to allow discussion of topics
concerned with OSLib. They are:

      oslib-user -- for comments from users, as opposed to developers of the
      library. Subscribing and posting are both open.
      mailto:<oslib-user-subscribe@compton.nu>

      oslib-team -- for discussions amongst the developer 'team'. Subscribing
      and posting are both moderated.
      mailto:<oslib-team-subscribe@compton.nu>

      oslib-announce -- announcements about OSLib. Subscribing is open;
      posting moderated.
      mailto:<oslib-news-subscribe@compton.nu>

Installation
------------
Having downloaded the appropriate archive for your system - the one named
'OSLib' is suitable for directory structures with less than 77 files per
directory, whereas 'OSLibRO4' fequires a file system which can handle more
than 77 files per directory - you will see a number of
files, and one directory.

The file you are presently reading is OSLib-readme, and contains the basic
introduction to OSLib, and how to install it.

Make sure you read the "Copying" text so that you know what you may and may
not legally do.

The "ChangeLog" text contains details on how OSLib has evolved over the
years, and will be useful if you're upgrading, and and you find it's
behaviour to be subtly different.

The "API_readme" file describes the relationships between OSLib names, and
the associated PRM descriptions.

Finally, the OSLib directory is what it's all about; you should copy this to
a suitable place on your hard disc; probably in the same place as your other
libraries. Don't put it too low down in the directory structure; if you do
the path name will become too long for the system to resolve it. Two or three
levels down should be OK. It is possible to use OSLib within the archive, but
you will find it will significantly slow down the compilation process.

Using OSLib
-----------
At the top level in the OSLib directory you will find an Obey file named
SetVars. When this is run, the OSLib: path is set up. If you want to change
it, that's fine, but the default is really all you need. Make sure SetVars is
executed before you attempt to build anything using the library.

Compiling
---------
In any source file from which you want to call an OSLib veneer, you will
have to specify where it is to be found with a line of the type
#include "oslib/wimp.h".  In this example, the "oslib/" prefix ensures that
"wimp.h"  is  loaded from oslib, as opposed to any  other library. When
compiling, you need to ensure that the compiler can locate OSLib, by
specifying "-IOSLib:" on the command line.

A typical Norcroft C compiler command line for a C module using OSLib and 
OSLibSupport will be similar to:

    cc -c -afh -apcs 3/32 -IOSLibSupport:,OSLib:,C: -o foo.o foo.c

For GCC the equivalent command would be (note that there are better ways of
using GCC to compile and link):

    gcc -c -IOSLibSupport:,OSLib: -o foo.o foo.c

Please refer to your compiler manual for details on the use of the command line.

  The above gives the preferred way of using OSLib. However, much existing
code will not contain the "oslib/" prefix in the #include line. If you don't
want to change things, and are not worried about name collisions, then you
may specify "-IOSLibInclude:"  on the command line, which will allow the
compiler to locate files without the prefix. In new code, always use the
prefixed form for safety.

Linking
-------
The only OSLib-specific precaution required for the linking stage is to include 
OSLib (and OSLibSupport, if required) on the command line.

A typical Link command would be:

   link foo1.o foo2.o ... OSLibSupport:OSLibSupport.o OSLib:OSLib.o C:stubs.o

Again, this is inherent in the tool usage, there is nothing special about 
its use with OSLib.

Help is at hand
---------------

If, having read, and re-read this documentation, and the related FAQ on the
web site, you still have problems, then subscribe to the OSLib-User mail
list, as described on the web site, and ask your question there.

The OSLib web-site is at http://ro-oslib.sourceforge.net.

--------------------
Tony van der Hoff.
20030227
